generic
package v8.Class_Handle.Class_Persistent is
   type Persistent_Object (<>) is new Handle_Object with private;
   type Persistent is access all Persistent_Object;
   -- An object reference that is independent of any handle scope.  Where
   -- a Local handle only lives as long as the HandleScope in which it was
   -- allocated, a Persistent handle remains valid until it is explicitly
   -- disposed.
   --
   -- A persistent handle contains a reference to a storage cell within
   -- the v8 engine which holds an object value and which is updated by
   -- the garbage collector whenever the object is moved.  A new storage
   -- cell can be created using Persistent :  : New and existing handles can
   -- be disposed using Persistent :  : Dispose.  Since persistent handles
   -- are passed by value you may have many persistent handle objects
   -- that point to the same storage cell.  For instance, if you pass a
   -- persistent handle as an argument to a function you will not get two
   -- different storage cells but rather two references to the same
   -- storage cell

   function Create
     (Source : Pointer
     ) return Persistent;
   -- Creates a new persistent handle for an existing local or
   -- persistent handle.


   procedure Dispose (this : in out Persistent_Object);
   -- Releases the storage cell referenced by this persistent handle.
   -- Does not remove the reference to the cell from any handles.
   -- This handle's reference, and any other references to the storage
   -- cell remain and IsEmpty will still return false.


   type Weak_Reference_Callback is access procedure
     (Object : Persistent;
      Parameter : Address);

   procedure Make_Weak
     (this : in out Persistent_Object;
      Callback_Data : System.Address := System.Null_Address;
      Callback      : Weak_Reference_Callback);
   -- Make the reference to this object weak.  When only weak handles
   -- refer to the object, the garbage collector will perform a
   -- callback to the given V8::WeakReferenceCallback function, passing
   -- it the object reference and the given parameters.


   procedure Clear_Weak (this : in out Persistent_Object);
   -- Clears the weak reference to this object.


   procedure Mark_Independent (this : in out Persistent_Object);
   -- Marks the reference to this object independent. Garbage collector
   -- is free to ignore any object groups containing this object.
   -- Weak callback for an independent handle should not
   -- assume that it will be preceded by a global GC prologue callback
   -- or followed by a global GC epilogue callback.


   function Is_Near_Death (this : Persistent_Object) return Boolean;
   -- Checks if the handle holds the only reference to an object.


   function Is_Weak (this : Persistent_Object) return Boolean;
   -- Returns true if the handle's reference is weak.

   procedure Set_Wrapper_Class_Id
     (this     : in out Persistent_Object;
      Class_Id : uint16_t);
   -- Assigns a wrapper class ID to the handle. See RetainedObjectInfo
   -- interface description in v8-profiler.h for details.


private
   type Persistent_Object is new Handle_Object with null record;

   pragma Convention(CPP, Weak_Reference_Callback);

end v8.Class_Handle.Class_Persistent;
